Architektura API pro generování XML

Přehled tří přístupů

Tento dokument shrnuje diskuzi o různých architektonických přístupech k vytváření XML dokumentů v XmlStackBuilder, zejména s ohledem na použití z FoxPro přes wwDotnetBridge.

1. Stack API (současná implementace)

Princip:

• Využívá vzor Push/Pop pro práci s elementy
• Jediný centrální objekt builder spravuje interní zásobník
• Metody Push() přidávají elementy na zásobník, Pop() je odebírá

Příklad použití (FoxPro):

LOCAL loBridge, loBuilder

loBridge = getwwBridge()
loBridge.LoadAssembly("XmlStackBuilder.Core.dll")
loBuilder = loBridge.CreateInstance("XmlStackBuilder.Core.XmlStackBuilder")

loBuilder.Push("Hlavicka")
loBuilder.PushValue("mesic", "12")
loBuilder.PushValue("rok", "2024")
loBuilder.Pop()  && ukončí Hlavicka

lcXml = loBuilder.Build()

Výhody pro FoxPro:

• Minimální overhead přes COM (jeden objekt)
• Jednoduchá syntax bez řetězení metod
• Rychlé volání přes wwDotnetBridge
• Intuitivní Push/Pop model

Nevýhody:

• Nutnost pamatovat si strukturu zásobníku
• Chyby při nespárovaných Push/Pop
• Méně "objektový" přístup

2. Object Tree API

Princip:

• Každý XML element je samostatný objekt
• Vztahy parent-child jsou explicitní
• Hierarchie objektů odpovídá struktuře XML

Příklad použití (C#):

var root = new XmlElement("Hlavicka");
var mesic = new XmlElement("mesic");
mesic.SetValue("12");
root.AddChild(mesic);

var rok = new XmlElement("rok");
rok.SetValue("2024");
root.AddChild(rok);

string xml = root.ToXml();

Příklad použití (FoxPro):

LOCAL loBridge, loRoot, loMesic, loRok

loBridge = getwwBridge()
loBridge.LoadAssembly("XmlStackBuilder.Core.dll")

loRoot = loBridge.CreateInstance("XmlStackBuilder.Core.XmlElement", "Hlavicka")

* Vytvoření child elementu
loMesic = loBridge.CreateInstance("XmlStackBuilder.Core.XmlElement", "mesic")
loMesic.SetValue("12")
loRoot.AddChild(loMesic)

* Další child element
loRok = loBridge.CreateInstance("XmlStackBuilder.Core.XmlElement", "rok")
loRok.SetValue("2024")
loRoot.AddChild(loRok)

lcXml = loRoot.ToXml()

Výhody:

• Explicitní objektová hierarchie
• Čitelná struktura kódu
• Možnost manipulace s jednotlivými elementy

Nevýhody pro FoxPro:

• Velký počet COM objektů (pomalé)
• Verbose syntax s mnoha mezikroky
• KRITICKÉ OMEZENÍ: FoxPro nepodporuje method chaining přes COM

  * Toto NEFUNGUJE ve FoxPro:
  loRoot.AddChild("mesic").SetValue("12")
  
  * Musíte použít:
  loMesic = loRoot.AddChild("mesic")
  loMesic.SetValue("12")
  

3. Fluent Builder API

Princip:

• Využívá lambda výrazy pro konfiguraci
• Plynulé rozhraní s method chaining
• Deklarativní syntax

Příklad použití (C#):

var xml = new FluentXmlBuilder()
    .WithRoot("Dphdp3")
    .WithHlavicka(h => {
        h.Mesic(12);
        h.Rok(2024);
        h.DatVytvor(DateTime.Now);
    })
    .WithPolozky(p => {
        p.AddPolozka(pol => {
            pol.Castka(1500.50m);
            pol.Popis("Test");
        });
    })
    .Build();

Důvody, proč NELZE použít z FoxPro:

1. FoxPro nemá lambda výrazy

   // C# lambda - neexistuje ekvivalent ve FoxPro
   .WithHlavicka(h => { h.Mesic(12); })
   

2. FoxPro nepodporuje Action delegáty přes COM

   // Tento typ parametru není přenositelný přes COM
   public FluentXmlBuilder WithHlavicka(Action<HlavickaBuilder> configure)
   

3. FoxPro nemá generické typy

   // Generika nefungují přes COM interop
   public class FluentXmlBuilder<T> where T : class
   

4. Method chaining nefunguje přes COM

   * Toto NEFUNGUJE ve FoxPro:
   loBuilder.WithRoot("Test").WithHlavicka(...).Build()
   

Výhody (pouze pro C#):

• Velmi čitelný a expresivní kód
• IntelliSense podpora
• Compile-time kontrola

Nevýhody:

• NEPOUŽITELNÉ z FoxPro
• Vyžaduje .NET 4.0+ pro lambda výrazy
• Složitější implementace

Srovnání pro FoxPro + COM

Doporučení

Pro FoxPro klienty (wwDotnetBridge)

Používejte Stack API - je to jediný praktický přístup pro FoxPro:

• Minimální COM overhead
• Jednoduchá syntax bez method chaining
• Rychlé a efektivní
• Žádné lambda výrazy nebo delegáty

Pro C# klienty

Můžete použít všechny tři přístupy:

• Stack API - dobrý výkon, jednoduchá implementace
• Object Tree - když potřebujete manipulaci s jednotlivými elementy
• Fluent Builder - nejelegantnější syntax, nejlepší developer experience

Závěr

Stack API je optimální volba pro XmlStackBuilder, protože:

1. Funguje perfektně z FoxPro (primární use case)
2. Je dostatečně jednoduchý pro C# klienty
3. Minimalizuje komunikační overhead přes COM
4. Nevyžaduje pokročilé .NET funkce (lambdas, generics)

FoxPro omezení, která vylučují alternativní přístupy:

• ❌ Žádné lambda výrazy
• ❌ Žádné Action delegáty přes COM
• ❌ Žádný method chaining přes COM
• ❌ Žádná podpora pro generické typy přes COM

Stack API je jediná architektura, která splňuje požadavky pro použití z FoxPro přes wwDotnetBridge.

API pro generování šablon a výstupů

Kromě Stack API pro sestavování XML nabízí XmlStackBuilder další API pro generování JSON šablon, renderování výstupů a konverzi FRX reportů.

Generování JSON šablon z cursor schema (CursorSchemaGenerator)

Automatické generování JSON šablon pro tabulkové sestavy z definice FoxPro kurzoru — bez nutnosti psát JSON ručně.

Dvě metody

Cursor schema — dva formáty

*--- CREATE TABLE formát ---
lcSchema = "CREATE TABLE U (Den D, Rada C(2), Doklad N(5), Castka N(15,2), Text C(30))"

*--- Plain formát ---
lcSchema = "Den D,Rada C(2),Doklad N(5),Castka N(15,2),Text C(30)"

*--- S FoxPro line continuation ---
lcSchema = "CREATE TABLE U (Den D;" + CHR(13) + CHR(10) + "  , Rada C(2))"

Podporované typy: C/Character, N/Numeric, D/Date, T/DateTime, L/Logical, M/Memo, I/Integer, B/Double, Y/Currency, V/Varchar, F/Float.

Options string

Formát: "key1:value1,key2:value2,..." — split na , (respektuje {}), pak na první :.

Groups — automatické generování skupin

Syntax: groups:stredisko;ucet+organizace;sn

• ; odděluje skupiny (od vnější k vnitřní)
• + odděluje compound klíče ve skupině (sloučí se do pole groupExpression)
• První (vnější) skupina: headerMode: "external", tableBreak: true
• Vnitřní skupiny: headerMode: "inline", tableBreak: false
• Label: "Stredisko {stredisko}" — Proper(fieldName) + placeholder
• sumLabel: "Celkem za {stredisko}"
• sumExpressions: automaticky ze všech numerických sloupců (N s decimals>0, Y, B) kromě noTotalColumns

Odhad šířek sloupců

Šířky se počítají v mm podle vzorce inspirovaného sfReport/makerepo2:

charWidthMm = fontPt × 0.6 × 25.4 / 72.0
gapMm       = 2 × (0.5 - 0.015 × fontPt) × charWidthMm
columnMm    = widthChars × charWidthMm + gapMm

Šířky v znacích podle typu:

Finální šířka = max(dataWidthMm, headerWidthMm).

printColumns

Dostupná šířka stránky (po odečtení 2×8mm margins):

Sloupce se přidávají zleva dokud kumulativní šířka nepřesáhne dostupnou šířku. Pokud se nevejdou všechny → "printColumns" v JSON.

Auto orientation ("auto"): zkusí portrait, pokud se nevejdou → landscape.

FoxPro příklady

*--- 1. Fragment columns (pro vložení do vlastní šablony) ---
lcColumns = loBuilder.GenerateColumnsFromSchema( ;
    "Den D,Rada C(2),Castka N(15,2)", ;
    "dataFontPt:8")

* Vrátí JSON:
* {
*   "columns": {
*     "den": { "label": "Den", "align": "center", "format": "dd.MM.yyyy", "width": "13.8mm" },
*     "rada": { "label": "Rada", "width": "7.1mm" },
*     "castka": { "label": "Castka", "align": "right", "format": "N2", "hideZero": true, "width": "25.6mm" }
*   }
* }


*--- 2. Kompletní report s groups a placeholdery ---
loBuilder.GenerateReportFromSchema( ;
    "C:\output\report.json", ;
    "CREATE TABLE U (Den D, Rada C(2), Stredisko C(3), Ucet C(3), " + ;
    "Castka N(15,2), Cizi N(15,2), Text C(30))", ;
    "dataFontPt:7" + ;
    ",groups:stredisko;ucet" + ;
    ",noTotalColumns:den;rada;stredisko;ucet;text" + ;
    ",title:{header.nadpis}" + ;
    ",tfiltr:{header.filtr}" + ;
    ",element:doklady")

* Vygeneruje kompletní JSON šablonu:
*   - renderer: "table"
*   - report: title, culture, dataFontPt, pageLayout, pageMarginMm
*   - header: filter s placeholderem
*   - pageHeader/pageFooter: {company}, {title}, {page}/{pages}, {date}
*   - sections: element, columns s šířkami, 2 groups se sumExpressions, grand total
*   - printColumns (pokud se nevejdou všechny)


*--- 3. Saldokonto s auto orientací ---
loBuilder.GenerateReportFromSchema( ;
    "C:\output\saldo.json", ;
    "Den D,Organizace C(15),Doklad C(10),MD N(15,2),D N(15,2),Saldo N(15,2)", ;
    "dataFontPt:6,orientation:auto,groups:organizace,noTotalColumns:den;doklad,element:pohyby")


*--- 4. Jednoduchý ceník bez skupin ---
loBuilder.GenerateReportFromSchema( ;
    "C:\output\cenik.json", ;
    "Kod C(10),Nazev C(40),Mj C(5),Cena N(12,2)", ;
    "noTotalColumns:kod;nazev;mj,element:polozky,title:Ceník zboží")


*--- 5. Široká sestava s compound skupinou ---
loBuilder.GenerateReportFromSchema( ;
    "C:\output\analyza.json", ;
    "Stredisko C(3),Ucet C(6),Organizace C(10),Doklad C(10),Text C(30)," + ;
    "MD N(15,2),D N(15,2),Zustatek N(15,2)", ;
    "dataFontPt:6" + ;
    ",orientation:landscape" + ;
    ",pageSize:A4" + ;
    ",groups:stredisko;ucet+organizace" + ;
    ",noTotalColumns:doklad;text" + ;
    ",element:pohyby" + ;
    ",culture:cs-CZ" + ;
    ",rowNumbers:group")

* Výsledek: compound skupina ucet+organizace →
*   "groupExpression": ["ucet", "organizace"]
*   "label": "Ucet + Organizace {ucet} {organizace}"

Příklad generovaného JSON

{
  "renderer": "table",
  "report": {
    "title": "{header.nadpis}",
    "culture": "cs-CZ",
    "dataFontPt": 7,
    "pageLayout": "paged",
    "pageMarginMm": 8
  },
  "header": {
    "filter": "{header.filtr}"
  },
  "pageHeader": {
    "left": "{company}",
    "center": "{title}",
    "right": "Strana {page} z {pages}",
    "heightMm": 10,
    "fromPage": 2
  },
  "pageFooter": {
    "left": "Vytištěno: {date}",
    "heightMm": 8
  },
  "sections": [
    {
      "element": "doklady",
      "columns": {
        "den": { "label": "Den", "align": "center", "format": "dd.MM.yyyy", "width": "13.8mm" },
        "rada": { "label": "Rada", "width": "7.1mm" },
        "stredisko": { "label": "Stredisko", "width": "14.5mm" },
        "ucet": { "label": "Ucet", "width": "7.1mm" },
        "castka": { "label": "Castka", "align": "right", "format": "N2", "hideZero": true, "width": "25.6mm" },
        "cizi": { "label": "Cizi", "align": "right", "format": "N2", "hideZero": true, "width": "25.6mm" },
        "text": { "label": "Text", "width": "30.8mm" }
      },
      "groups": [
        {
          "groupExpression": "stredisko",
          "label": "Stredisko {stredisko}",
          "headerMode": "external",
          "tableBreak": true,
          "sumExpressions": [
            { "field": "castka", "expr": "SUM(castka)", "format": "N2" },
            { "field": "cizi", "expr": "SUM(cizi)", "format": "N2" }
          ],
          "sumLabel": "Celkem za {stredisko}"
        },
        {
          "groupExpression": "ucet",
          "label": "Ucet {ucet}",
          "headerMode": "inline",
          "tableBreak": false,
          "sumExpressions": [
            { "field": "castka", "expr": "SUM(castka)", "format": "N2" },
            { "field": "cizi", "expr": "SUM(cizi)", "format": "N2" }
          ],
          "sumLabel": "Celkem za {ucet}"
        }
      ],
      "sumExpressions": [
        { "field": "castka", "expr": "SUM(castka)", "format": "N2" },
        { "field": "cizi", "expr": "SUM(cizi)", "format": "N2" }
      ],
      "sumLabel": "Celkem"
    }
  ],
  "_info": "Vygenerováno z cursor schema. Upravte element, labels a formáty dle potřeby."
}

Doporučené šířky sloupců v mm

Šířky se počítají podle vzorce:

charWidthMm = fontPt × 0.6 × 25.4 / 72
gapMm       = 2 × (0.5 − 0.015 × fontPt) × charWidthMm
paddingMm   = 2.1                           (CSS: 2×4px padding, fixed)
columnMm    = effWidth × charWidthMm + gapMm + paddingMm

Padding 2.1 mm = CSS td{padding:2px 4px} s border-collapse:collapse. Je uvnitř šířky sloupce, nezávisí na fontu. Korekce pro numerické sloupce: mezera (tisíce) = 0.35 znaku, tečka/čárka (des.) = 0.45 znaku.

Konstanty:

Šířky sloupců:

Dostupná šířka stránky (po odečtení 2×8 mm okrajů):

Poznámka: CursorSchemaGenerator standardně ořezává textové sloupce na maxLenString=20 znaků. C(30)–C(50) se tedy v generovaném JSON zobrazí jako 20 znaků, pokud nenastavíte maxLenString:30 (nebo vyšší) v options.

Přepočet šířek při změně velikosti písma

Při změně dataFontPt je potřeba přepočítat "width" na sloupcích.

Přesný vzorec (padding = fixní, content + gap = škálují se):

paddingMm = 2.1
width_nové = paddingMm + (width_staré - paddingMm) × (fontPt_nové / fontPt_staré)

Zjednodušený vzorec (chyba < 0.5 mm pro sloupce > 10 mm):

width_nové ≈ width_staré × (fontPt_nové / fontPt_staré)

Přepočítávací koeficienty:

Koeficienty = prostý poměr fontů (fontPt_nové / fontPt_staré): 7/8 = 0.875, 6/8 = 0.75 atd. Přesný vzorec s paddingem se vyplatí u úzkých sloupců (< 12 mm).

Typický workflow

1. FoxPro: loBuilder.GenerateReportFromSchema("sablona.json", lcSchema, lcOptions)
2. Uživatel: otevře sablona.json ve VS Code, upraví labels, přidá lookup, vizuální úpravy
3. FoxPro: loBuilder.Render("sestava.html", "sablona.json")   && nebo .pdf / .xlsx

Sjednocené Render API

*--- XML z interního builderu ---
loBuilder.Render("sestava.html", "definice.json")   && HTML výstup
loBuilder.Render("sestava.pdf", "definice.json")     && PDF výstup
loBuilder.Render("sestava.xlsx", "definice.json")    && XLSX výstup
loBuilder.Render("PRINTER:", "definice.json")         && tisk na výchozí tiskárnu

*--- XML z externího zdroje ---
loBuilder.RenderFromFiles("sestava.html", "definice.json", "data.xml")

Triple auto-detekce:

• JSON string vs. soubor: začíná { → string, jinak → cesta k souboru
• Typ šablony: JSON klíče "document"/"blocks" → document, "report"/"sections" → table
• Výstupní formát: z přípony — .html, .pdf, .xlsx

FRX konverze

*--- FRX XML export → JSON šablona (auto-detekce typu) ---
lcJson = loBuilder.ConvertFrxToJson(lcFrxXml)

*--- Všechny 3 soubory (JSON + vzorový XML + PRG) ---
loBuilder.ConvertFrxToAllFiles("C:\frx\CENIK.xml", "C:\output\")

*--- Vynucený typ (obchází auto-detekci) ---
loBuilder.ConvertFrxToDocumentJsonFile("C:\frx\INVUCKC.xml", "C:\output\invuckc.json")
loBuilder.ConvertFrxToTableReportJsonFile("C:\frx\CENIK.xml", "C:\output\cenik.json")

*--- Vynucený typ — všechny 3 soubory ---
loBuilder.ConvertFrxToDocumentAllFiles("C:\frx\INVUCKC.xml", "C:\output\")
loBuilder.ConvertFrxToTableReportAllFiles("C:\frx\CENIK.xml", "C:\output\")

*--- Vzorový XML a FoxPro PRG z JSON šablony ---
lcXml = loBuilder.GenerateSampleXmlFromJson(lcJson)
lcPrg = loBuilder.GenerateFoxProCodeFromJson(lcJson)

Auto-detekce typu (table vs. document) se řídí výškami bandů a počtem polí v FRX. Pro případy kdy detekce selže, existují varianty s vynuceným typem (TableReport/Document v názvu metody).

Placeholdery {element.field} v report properties

Všechny string properties v JSON sekcích report, header, footer, pageHeader, pageFooter podporují {element.field} placeholdery. Resolvují se při renderování z XML dat.

{
  "report": {
    "orientation": "{parametry.orientace}",
    "dataFontPt": "{parametry.fontpt}",
    "culture": "{parametry.kultura}"
  }
}

loBuilder.Push("parametry")
loBuilder.AddAttribute("orientace", "landscape")
loBuilder.AddAttribute("fontpt", "6")
loBuilder.AddAttribute("kultura", "en-US")
loBuilder.Pop()

loBuilder.Render("sestava.html", "definice.json")
&& → orientation=landscape, dataFontPt=6, culture=en-US

VS Code Editor s live preview

loBuilder.OpenReportEditor("C:\json\sablona.json", "C:\data\sample.xml")

Otevře VS Code s:

• JSON schéma IntelliSense (dynamické, s enum hodnotami z XML dat)
• Automatický live preview při uložení (RunOnSave + CLI renderer)
• preview.html s auto-refresh každé 2 sekundy

ShowProgress — průběh renderování

loBuilder.ShowProgress = .T.
loBuilder.Render("sestava.pdf", "sablona.json")   && dialog s průběhem
loBuilder.ShowProgress = .F.                        && vypnout

WinForms dialog na samostatném STA threadu:

• ProgressBar s číslem řádku (Řádek 450 / 1 200)
• Storno tlačítko pro přerušení (→ HtmlErrorMessage, Render() vrátí false)
• PDF fáze: řádky → formátování (marquee) → uložení (počet stran)
• Property přežívá Reset() i EndBatch() — nastaví se jednou, funguje pro všechny Render() volání
• Renderování zůstává synchronní — dialog jen vizualizuje průběh, žádná změna chování